Documentation/install.txt

Gerrit2 - Installation
======================

You need a SQL database to house the Gerrit2 metadata. Currently
PostgreSQL is the only supported database.

Important Links
---------------

PostgreSQL:

* http://www.postgresql.org/docs/[Documentation]

Downloading Gerrit
------------------

Current and past binary releases of Gerrit can be obtained from
the downloads page at the project site:

* http://code.google.com/p/gerrit/downloads/list[Gerrit Downloads]

Download any current `*.war` package.


Building Gerrit From Source
---------------------------

Alternatively, you can build the application distribution using
Maven from a source download obtained directly from Git:

====
 mkdir gerrit2
 cd gerrit2
 repo init -u git://android.git.kernel.org/tools/manifest.git

 (cd jgit/jgit-maven/jgit && mvn install)
 (cd sshd && mvn install)

 mvn clean package
 cp target/gerrit-*.war ...YOUR.DEST.../gerrit.war
====

The first build may take a while as dependencies are searched
for and downloaded from Maven distribution repositories.

Unfortunately you need to install snapshots of both JGit and
SSHD to your local Maven repository (typically under `~/.m2`).
These core dependencies are still under active development and have
not made final releases yet.

Apache Maven:

* http://maven.apache.org/download.html[Download]
* http://maven.apache.org/run-maven/index.html[Running Maven]

Apache SSHD:

* http://mina.apache.org/sshd/[Apache SSHD]


Setting up the Database
-----------------------

Currently PostgreSQL is the only supported database. H2 may also
work, but hasn't been tested in a while. The primary concern is
having support for the database in the gworm project.

PostgreSQL
~~~~~~~~~~

Create a Gerrit specific user as a normal user (no superuser access)
and assign it an encrypted password:

====
 createuser -A -D -P -E gerrit2
====

Create the database to store the Gerrit metadata, and set the user
you just created as the owner of that database:

====
 createdb -E UTF-8 -O gerrit2 reviewdb
====

Initialize the Schema
---------------------

Create the Gerrit 2 Tables
~~~~~~~~~~~~~~~~~~~~~~~~~~

Either run CreateSchema from the command line:

====
 java -jar gerrit.war --cat extra/GerritServer.properties_example >GerritServer.properties
 edit GerritServer.properties

 java -jar gerrit.war CreateSchema
====

Or, run the application once in a container to force it to initialize
the database schema before accessing it. (See below for deployment
setup documentation.) If you use this approach, it is recommended
that you stop the application before continuing with the setup.

Add Indexes
~~~~~~~~~~~

A script should be run to create the query indexes, so Gerrit
can avoid table scans when looking up information. Run the
`sql/query_index.sql` script through your database's query tool.

e.g. with PostgreSQL:

====
 java -jar gerrit.war --cat sql/query_index.sql | psql reviewdb
====

Configure site_path
~~~~~~~~~~~~~~~~~~~

This directory holds server-specific configuration files and
assets used to customize the deployment. Gerrit needs read
access (but not write access) to the directory. The path
is stored in `system_config.site_path`, so you will need to
update the database with this value.

====
 mkdir /home/gerrit/cfg
 cd /home/gerrit/cfg

 ssh-keygen -t rsa -P '' -f ssh_host_rsa_key
 ssh-keygen -t dsa -P '' -f ssh_host_dsa_key

 psql -c "UPDATE system_config SET site_path='/home/gerrit/cfg'" reviewdb
====

The SSH keys generated here are used as the host keys for the
internal SSH daemon run by Gerrit. You may wish to backup these
key files to ensure they can be restored in the event of a disaster.

The private key files (`ssh_host_rsa_key`, `ssh_host_dsa_key`) should
be readable *only* by the account that is executing Gerrit2's web
application container. It is a security risk to make these files
readable by anyone else.

Create Git Repository Base
~~~~~~~~~~~~~~~~~~~~~~~~~~

This directory holds the Git repositories that Gerrit knows about
and can service. Gerrit needs write access to this directory and
any Git repository stored within it.

====
 mkdir /srv/git
 psql -c "UPDATE system_config SET git_base_path='/srv/git'" reviewdb
====

You may wish to consider also exporting this directory over the
anonymous git:// protocol, as it is more efficient than Gerrit's
internal ssh daemon. See the `git-daemon` documentation for details
on how to configure this if anonymous access is desired.

* http://www.kernel.org/pub/software/scm/git/docs/git-daemon.html[man git-daemon]

Futher Configuration
~~~~~~~~~~~~~~~~~~~~

Gerrit2 supports some site-specific customizations. These are
optional and are not required to run a server, but may be desired.

* link:config-sso.html[Single Sign-On Systems]
* link:config-replication.html[Git Replication/Mirroring]
* link:config-headerfooter.html[Site Header/Footer]
* link:config-gitweb.html[Gitweb Integration]
* link:config-gerrit.html[Other system_config Settings]

Application Deployment
-----------------------

Jetty
~~~~~

These directions will configure Gerrit as the default web
application, allowing URLs like `http://example.com/4543` to
jump directly to change 4543.

Download and unzip a release version of Jetty. From here on we
call the unpacked directory `$JETTY_HOME`.

* http://dist.codehaus.org/jetty/[Jetty Downloads]

Install the JDBC drivers, using either the ones that come embedded
with Gerrit, or by downloading them yourself from their mirrors:
====
 java -jar gerrit.war --cat lib/c3p0-0.9.1.2.jar >$JETTY_HOME/lib/plus/c3p0-0.9.1.2.jar
 java -jar gerrit.war --cat lib/postgresql-8.3-603.jdbc3.jar >$JETTY_HOME/lib/plus/postgresql-8.3-603.jdbc3.jar
====

Copy Gerrit into the deployment:
====
 java -jar gerrit.war --cat extra/jetty_gerrit.xml >$JETTY_HOME/contexts/gerrit.xml
 cp gerrit.war $JETTY_HOME/webapps/gerrit.war

 rm -f $JETTY_HOME/context/test.xml
====

Edit `$JETTY_HOME/contexts/gerrit.xml` to correctly configure the
database and outgoing SMTP connections, especially the user and
password fields.

To start automatically when the system boots, consider a start
script such as the following in `/etc/init.d/gerrit2-jetty`

====
 #!/bin/sh
 
 export JETTY_HOST=127.0.0.1
 export JETTY_PORT=8081
 export JETTY_USER=gerrit2
 export JETTY_PID=/var/run/jetty$JETTY_PORT.pid
 export JETTY_HOME=/home/$JETTY_USER/jetty
 export JAVA_HOME=/usr/lib/jvm/java-6-sun-1.6.0.07/jre
 
 JAVA_OPTIONS=""
 JAVA_OPTIONS="$JAVA_OPTIONS -Djetty.host=$JETTY_HOST"
 export JAVA_OPTIONS
 
 exec $JETTY_HOME/bin/jetty.sh "$@"
====

To deploy on port 80, or to use SSL, you should configure Jetty
to listen on another port, such as 127.0.0.1:8081 (like the start
script above does) and then follow the <<apache2,reverse proxy>>
section below.

[TIP]
Under Jetty, restarting the web application (e.g. after modifying
`system_config`) is as simple as touching the config file:
`$JETTY_HOME/contexts/gerrit.xml`

Other Servlet Containers
~~~~~~~~~~~~~~~~~~~~~~~~

Deploy the `gerrit-*.war` file to your application server as
`gerrit.war`.

Configure the JNDI DataSource `jdbc/ReviewDb` for the Gerrit web
application context to point to the database you just created.
Don't forget to ensure your JNDI configuration can load the
necessary JDBC drivers.

('Optional') Configure the JNDI name `mail/Outgoing` for the web
application context to be a factory for a `javax.mail.Session`,
with the connection information necessary to send outgoing emails.
You may need to download and install the Java Mail JARs in your
container's classpath. If this is not configured, Gerrit will
function, but will not be able to send email.

[[apache2]]
Apache2 Reverse Proxy
~~~~~~~~~~~~~~~~~~~~~

Enable the necessary Apache2 modules:

====
 a2enmod proxy_http
 a2enmod disk_cache ; # optional, but helps performance
====

then setup a VirtualHost to proxy to Gerrit's servlet container,
setting the `ProxyPass` line to use the port number you configured
in your servlet container's configuration:

=======================================
<VirtualHost *>
 ServerName review.example.com
#
 ProxyRequests Off
 ProxyVia Off
 ProxyPreserveHost On
#
 <Proxy *>
Order deny,allow
Allow from all
 </Proxy>
 ProxyPass / http://127.0.0.1:8081/
#
 <IfModule mod_disk_cache.c>
CacheEnable disk /
CacheIgnoreHeaders Set-Cookie
 </IfModule>
</VirtualHost>
=======================================

To enable SSL, see the Apache server documentation.


Administrator Setup
-------------------

Login to Gerrit through the web interface, so that a user account
is initialized for you.

Add your newly created account to the "Administrators" group,
so that you can manage the site through the web interface:

====
 psql reviewdb
 INSERT INTO account_group_members
 (account_id, group_id)
 VALUES (
 (SELECT account_id FROM accounts
 WHERE preferred_email='you@example.com'),
 (SELECT admin_group_id FROM system_config)
 );
====

Group memberships are cached, so you need to either restart Gerrit,
or try flushing the caches over SSH.

Since SSH cache flushing requires being in the "Administrators"
group you may run into a chicken-and-egg problem, where you cannot
flush the cache to make yourself an administrator because you are
not yet an administrator. Therefore, restarting the application
is the recommended bootstrap technique.

To flush the server's caches over SSH, ensure you have an SSH key
(you can add one through the web UI under Settings, SSH Keys),
and then run:

====
 ssh -p 29418 you@example.com gerrit flush-caches
====

Project Setup
-------------

See link:project-setup.html[Project Setup] for further details on
how to register a project with Gerrit.